Skip to content

feat(text-editor): pluggable blocks, profiles and a block library - #211

Merged
clbotdev merged 24 commits into
mainfrom
feat/text-editor-blocks
Nov 20, 2026
Merged

clbotdev merged 24 commits into
mainfrom
feat/text-editor-blocks

Conversation

@clbotdev

Copy link
Copy Markdown
Contributor

Step 1 of the lesson-pages design (CourseLit docs/wip/lesson-pages.md, §3 and §10): pluggable blocks for @frontlit/text-editor, shipped as one release.

What changes

  • Block definitions and profiles. A server-safe BlockSchema and defineProfile in a new @frontlit/text-editor/blocks entry (no React). One profile builds the Tiptap schema/extensions, Markdown parser and serializer, validator with diagnostics, renderer map and a machine-readable formatReference.
  • Block library (off unless listed): Image, Video, Audio, PDF, File, Embed, plus Callout, Tabs, Accordion and Steps moved out of src/docs. Cards, Code group, Type table and frontmatter stay docs-only.
  • Default and docs setups rebuilt on profiles. Schemas are identical to before; docs Markdown output is byte-identical; all existing docs tests pass unchanged. profile still takes "default" | "documentation" and now also a profile object.
  • Availability. Editor unavailable={{ embed: "…" }} greys blocks out in the / menu and Insert menu. validateContent(profile, next, { previous, unavailable }) refuses an increase in the count over previous (block_unavailable, with the reason).
  • Editing UX. / insert menu filtered as you type, a drag handle per block, a settings popover per block, and MediaPickerContextProvider (image/video/audio/pdf/file → { id, previewUrl }). ImagePickerContextProvider keeps working.
  • Renderer. TextRenderer takes profile objects, host components per block (blocks={{ quiz: LearnerQuiz }}) and resolveMedia. React elements only; Embed code runs only in a srcdoc iframe with sandbox="allow-scripts allow-popups allow-forms".
  • Boundary. src/core and src/ui never import from src/docs; src/boundary.test.ts walks the import graph and fails with the import chain.
  • Security (§10). Link/image URL rules, video URLs reduced to provider + ID with fixed player URLs, raw HTML and JSX expressions refused, byte cap before parsing plus node/depth limits, base64 images only where the profile allows (default editor yes, docs no).

Verification

  • bun run --filter @frontlit/text-editor test: 196 tests (115 existing docs tests unchanged).
  • Whole repo: bun run typecheck, bun run lint, bun run format:check, bun run test (api 792, web 97, sites 86, page-builder 63, text-editor 196) and bun run build all pass.
  • Old vs new on every Markdown file in the repo: identical parse results, diagnostics and serialized Markdown.
  • Old vs new TextRenderer: identical HTML for every parsed docs page in both profiles, with and without a theme.
  • apps/docs built on origin/main and on this branch: all 211 prerendered pages have identical HTML apart from the client-chunk list.
  • Browser smoke in apps/docs with a temporary lesson-profile demo, not committed: / menu filtering, Video from a YouTube URL, Audio from the media picker, settings caption set and cleared, Embed greyed out with its reason, the availability diagnostic, and moving blocks with the drag handle. The default editor was also checked: menus, base64 upload and /table.

Notes for CourseLit

  • option, details, summary and section are CommonMark HTML block names. A one-line <Option …>text</Option> is therefore read as raw HTML and refused. Write nested tags across several lines, as the serializer does. The §4.2 example needs that.

…r insert, pointer drag handle

Found in the local e2e run:
- '/heading 2' closed the menu at the space; Escape left the hidden menu taking Enter and arrows.
- Inserting Tabs or Steps left the cursor in the last tab or step body.
- The drag handle relied on HTML5 drag and drop; it now follows the pointer with a drop line and moves the block in one undoable transaction.
@clbotdev

Copy link
Copy Markdown
Contributor Author

Local e2e on the full stack (API, web and sites against a fresh database):

  • Articles (default profile): typed through / (Heading 2, bullet list, table), inserted an image with the host picker (Unsplash URL), moved a block with the drag handle, undid the move, autosaved, published. The public site renders it.
  • Documentation (docs profile): inserted Callout, Tabs, Steps, Cards, Accordion, Code group and Type table through /. Cleared and partly typed block fields (callout title, tab label, card title) and autosave stayed green. Published, and the public site renders every block. The stored draft_markdown matches the serializer output byte for byte.
  • API Markdown: a PATCH with valid Markdown and a Callout returns 200 and loads in the editor. javascript: links get UNSAFE_URL and raw HTML gets UNSUPPORTED_NODE, each with line and column.
  • Page builder: typed /quote in the rich-text field; the draft saved, the preview rendered it, and the published /privacy page shows it.

Fixed along the way:

  • /heading 2 closed the menu at the space. After Escape, the hidden menu still took Enter.
  • Inserting Tabs or Steps left the cursor in the last tab or step.
  • The drag handle used HTML5 drag and drop. It now follows the pointer, shows a drop line and moves the block in one undoable step.
  • The editor caused a hydration mismatch in Next apps.
  • The apps/docs text-editor page now documents pluggable blocks.

Not part of this PR: on a plain-http dev origin, the docs publish dialog's "Check changes" fails because crypto.randomUUID needs a secure context (apps/web code). It works over https and localhost.

…ploads

A Vite app on the workspace @frontlit/text-editor with every library block.
Its dev server stands in for a host backend (upload signature and seal), so
Image, Video, Audio, PDF and File blocks upload to MediaLit over tus and
store only the media ID; resolveMedia maps IDs to URLs in the editor and the
renderer. Also shows unavailable, validateContent and serializeMarkdown.
The menu was placed once when it opened, while its list was still empty, so
flip() saw room below the caret and never moved it once the items arrived.
Re-place it with autoUpdate whenever it resizes or the page scrolls, cap its
height to the space available (it scrolls past that), and keep the
highlighted entry scrolled into view.
…n readers

Found in an axe and keyboard pass over the editor with every block:

- Block bar text was 4.34:1 on its background; bars now use a slightly
  darker muted colour (WCAG 1.4.3).
- The editing area had no role or name; it is now a labelled textbox
  (new ariaLabel prop, default "Rich text editor").
- The / menu was silent to screen readers; the editor now points
  aria-controls / aria-activedescendant at it while focus stays in the text.
- Blocks could only be moved by dragging; Mod-Shift-Up/Down moves the block
  at the cursor. The handle leaves the accessibility tree.
- Tab from a block's text went to the first block's controls; Alt-F10 now
  focuses the current block's controls and Escape returns to its text.
- Settings popovers now take focus when opened and give it back to their
  button on Escape (it fell to <body>).
- Item remove buttons say which item ("Remove tab 2").

Also adds the README section the docs page already linked to: custom blocks,
keyboard and screen reader use.
…able

The highlighted entry had no colour: the menu is portaled to <body>,
outside the editor's tokens, so bg-muted painted nothing in hosts without
global tokens. It now uses aria-selected styles with fallbacks and a bar in
the primary colour (and a system outline in forced-colours mode).

Arrow keys also snapped back while the pointer rested over the menu: each
step scrolled an item under it and mouseenter stole the highlight. Hover now
follows mousemove, and steps read the latest index, so fast key repeats
don't drop.

Adds the usual list keys: Ctrl+N/P, Tab/Shift+Tab, Home/End and
PageUp/PageDown; the highlight starts on the first usable entry.
The / menu now shows entries in sections (Text, Media, Layout, or a block's
own insert.group, default "Blocks") with a one-line description under each
label, icons in tiles, and a footer listing the keys. Library and docs
blocks carry descriptions; BlockUi.insert gains an optional group.

Each section is an ARIA group labelled by its heading; options are named by
their label and described by their description (or the reason they are
unavailable). The menu gets the editor's tokens, since it is portaled to
<body>, and description text on the highlight tint is darkened to 4.5:1.
Filtering still matches labels and keywords only, so short queries stay
precise.
A catch-all `.ProseMirror iframe` rule (from the old YouTube embed) gave
every iframe in the editor a black background, rounded corners and a 16:9
ratio. Embed frames are transparent, so their default black text was drawn
on black. The video backdrop now lives on .te-video__frame only.
…s, and an agent-readable content format

Blocks (library, enabled in the documentation profile, so the API and MCP
accept them in Markdown):
- <Button label href variant>: a link styled as a button; URLs go through
  the same safety checks as links.
- <WebPreview url title description image>: a link card the author or
  agent fills in (no server-side fetching).
- <H5P src title height>: an H5P activity in a frame, only from allowed
  hosts (h5p({ hosts }), default h5p.org and *.h5p.com).
- Callout gains a success type, and the / menu offers Warning, Tip,
  Success and Danger presets (BlockUi.variants).
URL fields in the editor store a value only once the block's own check
accepts it, so autosave never sees a half-typed URL; errors are announced.

For agents:
- contentFormat() / describeContentFormat() in @frontlit/text-editor/docs
  describe the format (every block, props, types, an example, limits).
- schema/content.v1.json is generated from it (schema:generate; a test fails
  when stale) and served at /schema/content.v1.json on every site.
- MCP create/update tools describe their markdown field from it, so new
  blocks need no tool edits; REST contract fields point to the URL.
Quick start with a complete component, a glossary of the core ideas,
choosing what the editor allows (base nodes, marks, heading levels and the
block library with Markdown forms and options), removing, hiding or
disabling blocks (and what happens to existing content), media with
pickMedia/resolveMedia, a step-by-step guide to adding a custom block,
changing built-in blocks, server validation and Markdown, rendering in
server components, keyboard use, agents, styling and an exports table.
Every snippet was type-checked against the package.
Incomplete blocks: attributes can be requiredToPublish (Button href,
WebPreview url, H5P src). The editor still saves them empty while the
author types, but incompleteBlocks(profile, content) reports them as
INCOMPLETE_BLOCK diagnostics that block publishing, never saving. Docs
publishing now includes them, and the API refuses Markdown from REST and
MCP that holds one, so an agent can't create an invisible button. (Making
the prop required in Markdown itself would have broken autosave: drafts
round-trip through Markdown.)

Reference: blocks can document Markdown-only props (docs.props), so
<Tabs items>, <Card icon>, <TypeTable type> and <Video url> are listed;
child tags (<Tab value>, <Card>, <Accordion>, <Step>) get their own lines;
the syntax line spells out the accepted literals ("text", {42}, {true},
{["a"]}, {{ k: "v" }}, {<Icon />}); and the description tells agents to
upload files with get_media_upload_signature / register_media and use the
returned URL.
…ct updates

Articles and product updates went live without any check, so a Button
saved without its link (from the editor or a JSON write) published as an
invisible block. Docs already blocked this.

- publish_article / publish_product_update (and REST publish) refuse a
  draft with incomplete blocks: 422 INCOMPLETE_BLOCK with the list.
- Every article and product-update response (get, list, create, update,
  publish; REST and MCP) carries publishable and diagnostics, as docs do,
  so agents see blockers on save without a separate validate call.
- The article and product-update editors show the blockers in a banner and
  disable Publish with that reason.
…target

Cross-platform images were built entirely under QEMU emulation (an arm64
image on an x86 machine took about an hour). Install and build stages now
run on $BUILDPLATFORM: their output is JavaScript, identical for every
target. Only the runtime stage, and the API's production install, run as
the target platform.

sharp is the one native module in Next's standalone output: the build stage
fetches its binaries for the target (bun install --cpu/--os, at the
lockfile's version) and the runtime stage places them beside each traced
copy of sharp.
Tables could only grow: the insert menu (+) held "Add table row", "Add
table column" and "Remove table", and nothing deleted a row or column.

With the cursor in a table, a bar above it now inserts a row above or
below, deletes the row, inserts a column left or right, deletes the
column, toggles the header row (rich tables only: Markdown tables always
have one) and deletes the table. It's a toolbar: Alt-F10 reaches it from
the cell, arrows and Home/End move between controls, Escape returns to the
cell, and each control names what it acts on ("Delete row 3"). The old
entries leave the insert menu.

Also: export button(), webPreview() and h5p() from the main entry (they
were only on /blocks), and give the example app tables and those blocks.
…e cursor in the block

Found in a browser smoke of the docs editor:

- "/warning" inserted a plain info callout: the filter kept menu order, so
  "Callout" (keyword "warning") came before "Warning callout". Entries
  whose label matches now rank first; sections stay together.
- After an insert the cursor could land in the block above. insertBlock
  only moved it when the insert left it inside the new block; it now finds
  the block, puts the cursor in its first text, or on the line after it
  for blocks without text (Button, Web preview, H5P, an empty card grid).
- The scrolling / menu list failed axe scrollable-region-focusable. It is
  focusable now and hands focus straight back to the editor.
The handle looked for the block under a point 24px inside the editor's
left edge, using posAtCoords. In the admin editors that point sits in
the content padding, where no position resolves, so the handle never
appeared. topLevelBlockAt now finds the block from the blocks' boxes at
the pointer height; each block owns the gap below it, so the handle
doesn't flicker between paragraphs.
Autolink also makes Tiptap's link mark inclusive, so text typed at the
end of a link joined it and a link could not be ended by typing (not even
spaces). Keep autolink; make the mark non-inclusive.
@clbotdev
clbotdev merged commit 2c8a44b into main Nov 20, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants